/**
 * Created On: Jul 14, 2012
 */
package com.athena.dal.dao;

import java.io.Serializable;
import java.util.List;
import java.util.Map;

import javax.persistence.EntityManager;

/**
 * A contract for generic DAO.
 * 
 * @author Ashish Kumar Sinha <aksinha.mail@gmail.com>
 * Version 1.0
 */
public interface GenericDao {
	
	/**
	 * to get hold of the entity manager.
	 * @return
	 */
	public EntityManager getEntityManager();
	
	/**
	 * to find an entity by its ID.
	 * @param entityClass - the entity class
	 * @param ID - the ID of the entity.
	 * 
	 * @return - the entity object if a row exists in the database for the ID. NULL otherwise.
	 */
	public <T> T findById(Class<T> entityClass, final Serializable ID);
	
	/**
	 * to find an entity by a name query
	 * 
	 * @param entityClass - the entity class
	 * @param queryName - the name of the query
	 * @param parameters - the map of the parameter name and the value object
	 * 
	 * @return - the single instance of the entity class as fetched from the database.
	 */
	public <T> T findByNameQuery(Class<T> entityClass, final String queryName, Map<String, Object> parameters);
	
	/**
	 * to find a list of the entity indentified by a name query
	 * 
	 * @param entityClass - the entity class
	 * @param queryName - the name of the query
	 * @param parameters - the map of the parameters name and the value object
	 * 
	 * @return - the list of the instances of the entity class as fetched from the database through the specified named query.
	 */
	public <T> List<T> findAllByNameQuery(Class<T> entityClass, final String queryName, Map<String, Object> parameters);
	
	/**
	 * to create or update an entity into the database.
	 * 
	 * If the entity has an ID, and the ID exists in the database, the database row is updated with entity object.
	 * Otherwise, a new entry is created in the datbase.
	 * 
	 * @param entity - the entity object.
	 * @return - the saved entity (with its ID field holding a valid value).
	 */
	public <T> T createOrUpdate(T entity);
	
	/**
	 * to create an entity in the database.
	 * 
	 * If the entity has an ID, and the ID exists in the database, then entry is NOT created.
	 * Otherwise, a fresh entry is made in the database.
	 * 
	 * @param entity - the entity to be created.
	 * @return - the entity object if the entry has been successfully made in the database. NULL otherwise.
	 */
	public <T> T create(T entity);
	
	/**
	 * to update an entity in the database.
	 * 
	 * If the entity has an ID, and the ID exists in the database, then entry is updated.
	 * No fresh entry would be made in the database.
	 * 
	 * @param entity - the entity to be updated.
	 * @return - the entity object if the entry has been successfully updated in the database. NULL otherwise.
	 */
	public <T> T update(T entity);
	
	/**
	 * to delete an entity from the database.
	 * 
	 * @param entity - the entity to be deleted
	 * 
	 */
	public <T> void delete(T entity);
}
